Retrieves an icon definition. This function runs asynchronously.

OSErr PBDTGetIconAsync (
    DTPBPtr paramBlock
);

paramBlock

A pointer to a desktop parameter block.

function result

A result code.

DISCUSSION

Clear all fields (other than input fields) in the parameter block that you pass to Desktop Manager functions. The relevant fields of the parameter block for this function are:

• ioCompletionOn input, a universal procedure pointer to a completion function. A value of type IOCompletionUPP.
• ioResultOn return, the result code of the function. A value of type OSErr.
• ioDTRefNumOn input, the desktop database reference number. A value of type SInt16.
• ioTagInfoOn input, reserved; must be set to 0. A value of type SInt32.
• ioDTBufferOn input, a pointer to a buffer to hold the icon’s data. On return, a pointer to the bitmap returned in the buffer. A value of type Ptr.
• ioDTReqCountOn input, the requested size of the icon’s bitmap. You pass in the size in bytes of the buffer that you’ve allocated for the icon’s bitmap pointed to by ioDTBuffer; this value depends on the icon type. Be sure to allocate enough storage for the icon data; 1024 bytes is the largest amount required for any icon in System 7. You can use constants to indicate the amount of memory you have provided for the icon’s data. See “Icon Size Constants” for a description of the values you can use here.
• ioDTActCountOn return, the actual size of the icon’s bitmap. A value of type SInt32. If ioDTActCount is larger than ioDTReqCount, only the amount of data allowed by ioDTReqCount is valid.
• ioIconTypeOn input, the icon type. A value of type SInt8. For a description of the constants which you can use in this field, see “Icon Type Constants”.
• ioFileCreatorOn input, the icon’s file creator. A value of type OSType.
• ioFileTypeOn input, the icon’s file type. A value of type OSType.

The PBDTGetIcon function returns the bitmap for an icon that represents a file of a given type and creator. (For example, to get the icon for a file of file type 'SFWR' created by the application with a signature of 'WAVE', specify these two values in ioFileType and ioFileCreator.) You pass a pointer to a buffer for the icon bitmap in the ioDTBuffer field. You specify the desktop database in ioDTRefNum, the file creator in ioFileCreator, and the file type in ioFileType.

SPECIAL CONSIDERATIONS

All of the Desktop Manager functions may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt. Your application should not call Desktop Manager functions at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)